stringify-entities

What is stringify-entities?

The stringify-entities npm package is used for encoding special characters into HTML or XML entities. It is particularly useful when you need to ensure that text content is safely and correctly represented in HTML or XML documents, preventing issues related to unescaped characters.

What are stringify-entities's main functionalities?

Encode special characters in HTML

This feature allows you to convert characters that have special meaning in HTML into their corresponding HTML entities, thus preventing them from being interpreted as HTML code. This is useful for displaying plain text in web pages.

const stringify = require('stringify-entities');

const text = 'This & that';
const encodedText = stringify(text);
console.log(encodedText); // 'This & that'

Encode special characters in XML

This feature enables the encoding of characters into XML entities. By specifying options, you can control which characters to encode and whether to escape only those characters, making it flexible for different XML contexts.

const stringify = require('stringify-entities');

const text = 'AT&T';
const options = {subset: ['&'], escapeOnly: true};
const encodedText = stringify(text, options);
console.log(encodedText); // 'AT&T'

Other packages similar to stringify-entities

he

The 'he' package is another popular HTML entity encoder and decoder. It supports all HTML5 entities and provides robust decoding capabilities, which makes it more comprehensive in handling HTML entities compared to stringify-entities, which focuses primarily on stringifying.

entities

Similar to 'stringify-entities', the 'entities' package offers encoding and decoding of HTML/XML entities. It provides a more extensive set of functionalities including decoding, which is not a focus of stringify-entities. This makes 'entities' a more versatile choice for projects that require both encoding and decoding capabilities.

README

stringify-entities

Serialize (encode) HTML character references.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • stringifyEntities(value[, options])
• Algorithm
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This is a small and powerful encoder of HTML character references (often called entities). This one has either all the options you need for a minifier/formatter, or a tiny size when using stringifyEntitiesLight.

When should I use this?

You can use this for spec-compliant encoding of character references. It’s small and fast enough to do that well. You can also use this when making an HTML formatter or minifier, because there are different ways to produce pretty or tiny output. This package is reliable: '`' characters are encoded to ensure no scripts run in Internet Explorer 6 to 8. Additionally, only named references recognized by HTML 4 are encoded, meaning the infamous ' (which people think is a virus) won’t show up.

Install

This package is ESM only. In Node.js (version 14.14+, 16.0+), install with npm:

npm install stringify-entities

In Deno with esm.sh:

import {stringifyEntities} from 'https://esm.sh/stringify-entities@4'

In browsers with esm.sh:

<script type="module">
  import {stringifyEntities} from 'https://esm.sh/stringify-entities@4?bundle'
</script>

Use

import {stringifyEntities} from 'stringify-entities'

stringifyEntities('alpha © bravo ≠ charlie 𝌆 delta')
// => 'alpha © bravo ≠ charlie 𝌆 delta'

stringifyEntities('alpha © bravo ≠ charlie 𝌆 delta', {useNamedReferences: true})
// => 'alpha © bravo ≠ charlie 𝌆 delta'

API

This package exports the identifiers stringifyEntities and stringifyEntitiesLight. There is no default export.

stringifyEntities(value[, options])

Encode special characters in value.

Core options

options.escapeOnly

Whether to only escape possibly dangerous characters (boolean, default: false). Those characters are ", &, ', <, >, and `.

options.subset

Whether to only escape the given subset of characters (Array<string>). Note that only BMP characters are supported here (so no emoji).

Formatting options

If you do not care about the following options, use stringifyEntitiesLight, which always outputs hexadecimal character references.

options.useNamedReferences

Prefer named character references (&) where possible (boolean?, default: false).

options.useShortestReferences

Prefer the shortest possible reference, if that results in less bytes (boolean?, default: false).

⚠️ Note: useNamedReferences can be omitted when using useShortestReferences.

options.omitOptionalSemicolons

Whether to omit semicolons when possible (boolean?, default: false).

⚠️ Note: This creates what HTML calls “parse errors” but is otherwise still valid HTML — don’t use this except when building a minifier. Omitting semicolons is possible for certain named and numeric references in some cases.

options.attribute

Create character references which don’t fail in attributes (boolean?, default: false).

⚠️ Note: attribute only applies when operating dangerously with omitOptionalSemicolons: true.

Returns

Encoded value (string).

Algorithm

By default, all dangerous, non-ASCII, and non-printable ASCII characters are encoded. A subset of characters can be given to encode just those characters. Alternatively, pass escapeOnly to escape just the dangerous characters (", ', <, >, &, `). By default, hexadecimal character references are used. Pass useNamedReferences to use named character references when possible, or useShortestReferences to use whichever is shortest: decimal, hexadecimal, or named. There is also a stringifyEntitiesLight export, which works just like stringifyEntities but without the formatting options: it’s much smaller but always outputs hexadecimal character references.

Types

This package is fully typed with TypeScript. It exports the additional types Options and LightOptions types.

Compatibility

This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+ and 16.0+. It also works in Deno and modern browsers.

Security

This package is safe.

Related

• parse-entities — parse (decode) HTML character references
• wooorm/character-entities — info on character references
• wooorm/character-entities-html4 — info on HTML 4 character references
• wooorm/character-entities-legacy — info on legacy character references
• wooorm/character-reference-invalid — info on invalid numeric character references

Contribute

Yes please! See How to Contribute to Open Source.

License

MIT © Titus Wormer